<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Registering Custom Error Messages - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level3"><a href="girch.html">Using Annotations to Configure Managed Beans</a></p>
<p class="toc level4"><a href="girch.html#gircr">Using Managed Bean Scopes</a></p>
<p class="toc level5"><a href="girch.html#girep">Eager Application-scoped Beans</a></p>
<p class="toc level3 tocsp"><a href="bnawp.html">Application Configuration Resource File</a></p>
<p class="toc level4"><a href="bnawp.html#giqck">Ordering of Application Configuration Resource Files</a></p>
<p class="toc level3 tocsp"><a href="bnawq.html">Configuring Beans</a></p>
<p class="toc level4"><a href="bnawq.html#bnawr">Using the <tt>managed-bean</tt> Element</a></p>
<p class="toc level4"><a href="bnawq.html#bnaws">Initializing Properties Using the <tt>managed-property</tt> Element</a></p>
<p class="toc level5"><a href="bnawq.html#bnawu">Referencing a Java <tt>Enum</tt> Type</a></p>
<p class="toc level5"><a href="bnawq.html#bnawv">Referencing an Initialization Parameter</a></p>
<p class="toc level5"><a href="bnawq.html#bnaww">Initializing Map Properties</a></p>
<p class="toc level5"><a href="bnawq.html#bnawx">Initializing Array and List Properties</a></p>
<p class="toc level5"><a href="bnawq.html#bnawy">Initializing Managed Bean Properties</a></p>
<p class="toc level4 tocsp"><a href="bnawq.html#bnaxa">Initializing Maps and Lists</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3 tocsp"><a href="">Registering Custom Error Messages</a></p>
<p class="toc level4"><a href="#gkuhg">Using <tt>FacesMessage</tt> to Create a Message</a></p>
<p class="toc level4"><a href="#bnass">Referencing Error Messages</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnaxc.html">Registering Custom Localized Static Text</a></p>
<p class="toc level3"><a href="gireb.html">Using Default Validators</a></p>
<p class="toc level3"><a href="bnaxf.html">Configuring Navigation Rules</a></p>
<p class="toc level4"><a href="bnaxf.html#giqwk">Implicit Navigation Rules</a></p>
<p class="toc level3 tocsp"><a href="bnaxj.html">Basic Requirements of a JavaServer Faces Application</a></p>
<p class="toc level4"><a href="bnaxj.html#bnaxk">Configuring an Application With a Web Deployment Descriptor</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxl">Identifying the Servlet for Lifecycle Processing</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxm">Specifying a Path to an Application Configuration Resource File</a></p>
<p class="toc level5"><a href="bnaxj.html#bnaxn">Specifying Where State Is Saved</a></p>
<p class="toc level4 tocsp"><a href="bnaxj.html#giqxl">Configuring Project Stage</a></p>
<p class="toc level4"><a href="bnaxj.html#bnaxt">Including the Classes, Pages, and Other Resources</a></p>
<p class="toc level2 tocsp"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<p class="toc level2"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="bnawq.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="bnaxc.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnaxb"></a><h2>Registering Custom Error Messages</h2>
<a name="indexterm-791"></a><a name="indexterm-792"></a><p><a name="indexterm-793"></a>If you create custom error messages (which are displayed by the <tt>message</tt>
and <tt>messages</tt> tags) for your custom converters or validators, you must make them
available at application startup time. You do this in one of two ways:</p>


<ul><li><p>By queuing the message onto the <tt>FacesContext</tt> instance programmatically, as described in <a href="#gkuhg">Using <tt>FacesMessage</tt> to Create a Message</a></p>

</li>
<li><p>By registering the messages with your application using the application configuration resource file</p>

</li></ul>
<p>Here is an example of the section of the <tt>faces-config.xml</tt> file that registers
the messages for an application:</p>

<pre>&lt;application>
    &lt;resource-bundle>
        &lt;base-name>dukestutoring.web.messages.Messages&lt;/base-name>
        &lt;var>bundle&lt;/var>
    &lt;/resource-bundle>
    &lt;locale-config>
        &lt;default-locale>en&lt;/default-locale>
        &lt;supported-locale>es&lt;/supported-locale>
        &lt;supported-locale>de&lt;/supported-locale>
        &lt;supported-locale>fr&lt;/supported-locale>
    &lt;/locale-config>
&lt;/application></pre><p>This set of elements will cause your <tt>Application</tt> instance to be populated with
the messages that are contained in the specified resource bundle.</p>

<p><a name="indexterm-794"></a>The <tt>resource-bundle</tt> element represents a set of localized messages. It must contain the
fully qualified path to the resource bundle containing the localized messages (in this
case, <tt>dukestutoring.web.messages.Messages</tt>).</p>

<p>The <tt>locale-config</tt> element lists the default locale and the other supported locales. The
<tt>locale-config</tt> element enables the system to find the correct locale based on the
browser&rsquo;s language settings. </p>

<p>The <tt>supported-locale</tt> and <tt>default-locale</tt> tags accept the lowercase, two-character codes as defined by
ISO 639 (see <a href="http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt">http://ftp.ics.uci.edu/pub/ietf/http/related/iso639.txt</a>). Make sure that your resource bundle actually contains the
messages for the locales that you specify with these tags.</p>

<p>To access the localized message, the application developer merely references the key of
the message from the resource bundle.</p>



<a name="gkuhg"></a><h3>Using <tt>FacesMessage</tt> to Create a Message</h3>
<a name="indexterm-795"></a><a name="indexterm-796"></a><p>Instead of registering messages in the application configuration resource file, you can access
the <tt>ResourceBundle</tt> directly from managed bean code. The code snippet below locates an
email error message:</p>

<pre>String message = "";
...
message = ExampleBean.loadErrorMessage(context,
    ExampleBean.EX_RESOURCE_BUNDLE_NAME,
         "EMailError");
context.addMessage(toValidate.getClientId(context),
    new FacesMessage(message));</pre><p>These lines call the bean's <tt>loadErrorMessage</tt> method to get the message from the
<tt>ResourceBundle</tt>. Here is the <tt>loadErrorMessage</tt> method:</p>

<pre>public static String loadErrorMessage(FacesContext context,
     String basename, String key) {
    if ( bundle == null ) {
         try {
            bundle = ResourceBundle.getBundle(basename,
                 context.getViewRoot().getLocale());
        } catch (Exception e) {
            return null;
        }
    }
    return bundle.getString(key);
}</pre>

<a name="bnass"></a><h3>Referencing Error Messages</h3>
<p>A JavaServer Faces page uses the <tt>message</tt> or <tt>messages</tt> tags to access
error messages, as explained in <a href="bnarf.html#bnaso">Displaying Error Messages with the <tt>h:message</tt> and <tt>h:messages</tt> Tags</a>.</p>

<p>The error messages that these tags access include:</p>


<ul><li><p>The standard error messages that accompany the standard converters and validators that ship with the API. See Section 2.5.2.4 of the JavaServer Faces specification for a complete list of standard error messages.</p>

</li>
<li><p>Custom error messages contained in resource bundles registered with the application by the application architect using the <tt>resource-bundle</tt> element in the configuration file.</p>

</li></ul>
<p>When a converter or validator is registered on an input component, the appropriate
error message is automatically queued on the component.</p>

<p>A page author can override the error messages queued on a component by
using the following attributes of the component&rsquo;s tag:</p>


<ul><li><p><tt>converterMessage</tt>: References the error message to display when the data on the enclosing component can not be converted by the converter registered on this component.</p>

</li>
<li><p><tt>requiredMessage</tt>: References the error message to display when no value has been entered into the enclosing component.</p>

</li>
<li><p><tt>validatorMessage</tt>: References the error message to display when the data on the enclosing component cannot be validated by the validator registered on this component.</p>

</li></ul>
<p>All three attributes are enabled to take literal values and value expressions. If
an attribute uses a value expression, this expression references the error message in
a resource bundle. This resource bundle must be made available to the application
in one of the following ways:</p>


<ul><li><p>By the application architect using the <tt>resource-bundle</tt> element in the configuration file</p>

</li>
<li><p>By the page author using the <tt>f:loadBundle</tt> tag</p>

</li></ul>
<p>Conversely, the <tt>resource-bundle</tt> element must be used to make available to the application
those resource bundles containing custom error messages that are queued on the component
as a result of a custom converter or validator being registered on the
component.</p>

<p>The following tags show how to specify the <tt>requiredMessage</tt> attribute using a value
expression to reference an error message:</p>

<pre>&lt;h:inputText id="ccno" size="19"
    required="true"
    requiredMessage="#{customMessages.ReqMessage}" >
    ...
&lt;/h:inputText>
&lt;h:message styleClass="error-message" for="ccno"/></pre><p>The value expression that <tt>requiredMessage</tt> is using in this example references the error
message with the <tt>ReqMessage</tt> key in the resource bundle, <tt>customMessages</tt>.</p>

<p>This message replaces the corresponding message queued on the component and will display
wherever the <tt>message</tt> or <tt>messages</tt> tag is placed on the page.</p>


         </div>
         <div class="navigation">
             <a href="bnawq.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="bnaxc.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

